When building applications using service-oriented architecture, you have to pick the protocol to use to communicate between your services. There are a variety of protocols available out there. You could also create your own, though, in most cases, it is not a good idea.
The HTTP protocol has been the Web standard for the last 25 years, and it does not seem like it is about to change anytime soon. It certainly has a few drawbacks but also has the amazing advantages being massively deployed, and it is simple to understand, and simple to debug for humans. It is also cache-able and easy to transport on most networks; it is rarely blocked. The number of tools surrounding HTTP is huge, making it a perfect candidate for rapid development and easy debugging.
REST API#
A REST Web service (based on HTTP) has the advantage of being stateless.
There is no single source of truth on best practices for REST API. The first thing to read and follow is the HTTP RFC: this is the absolute reference that you cannot break no matter what. There are also a few other references that you should check, like HATEOAS, the OpenAPI Initiative or the OpenStack API Working Group Guidelines. These documents are a good source of ideas before deciding on how to design your API endpoints. They answer a lot of common questions around creating semantically accurate APIs.
In the software programming world, there is no shortage of frameworks for building a REST API, and Python is no exception. It has many Web libraries that make it possible to achieve this goal.
Note: The most popular framework in the Python world, Django, even has a layer offering this feature and it’s called Django REST Framework. I am not a particular fan of Django, which, while being nice to build websites, seems cluttered for this task. This is a matter of personal preference, and I do not see anything wrong about building a REST API with Django. The same might be said about many other Python frameworks out there.
Flask#
Flask is one of the most used Web frameworks in the Python ecosystem. It is a good pick for building a REST API: it is rather lightweight, modular, extendable, and it does provide basic functionality.
Many examples in this chapter use the http command line tool to interact with HTTP REST APIs. This tool comes from httpie, a Python command line interface that is simple to use for humans, making it easy to interact with web servers, and it has colorized output.
Coding Challenge: Group Membership
The WSGI Protocol